Skip to main content
The REST API provides comprehensive HTTP endpoints for managing your AI agents, executing tasks, and controlling knowledge bases from any programming language.

​
Overview

The REST API is your control plane for the xpander platform, enabling you to:
  • Manage Agents: Create, update, deploy, and delete AI agents
  • Execute Tasks: Invoke agents synchronously, asynchronously, or with streaming
  • Control Knowledge: Manage knowledge bases and documents
  • Access Toolkits: List and invoke tools across integrations

​
Base URL

https://api.xpander.ai

​
Authentication

All API requests require authentication via the x-api-key header: 
curl -X GET "https://api.xpander.ai/v1/agents" \
  -H "x-api-key: YOUR_API_KEY"

​
Quick Start

# List all agents
curl -X GET "https://api.xpander.ai/v1/agents" \
  -H "x-api-key: YOUR_API_KEY"

# Invoke an agent
curl -X POST "https://api.xpander.ai/v1/agents/{agent_id}/invoke" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "Analyze this data"
    }
  }'

​
API Endpoints

Agents

Create, manage, and invoke AI agents

Tasks

Monitor and manage task executions

Knowledge

Manage knowledge bases and documents

Toolkits

Access and invoke tools

​
Key Features

  • 🌐 Universal Access: Works with any programming language that supports HTTP
  • ⚡ Multiple Execution Modes: Sync, async, and streaming invocation
  • 📊 Complete CRUD: Full lifecycle management for all resources
  • 🔒 Secure: API key authentication with organization-level scoping
  • 📖 OpenAPI Spec: Complete OpenAPI 3.1 specification available

​
Response Format

All API responses follow a consistent JSON structure: 
{
  "id": "resource-id",
  "status": "completed",
  "created_at": "2025-11-05T20:00:00Z",
  ...
}

​
Error Handling

The API uses standard HTTP status codes:
  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized
  • 404 - Not Found
  • 422 - Validation Error
  • 500 - Internal Server Error
Error responses include detailed information: 
{
  "detail": [
    {
      "loc": ["body", "input"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

​
Rate Limits

The API implements rate limiting to ensure fair usage:
  • Standard: 100 requests per minute
  • Burst: 1000 requests per hour
Rate limit headers are included in responses: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699200000

​
Next Steps

Agent Endpoints

Explore agent management endpoints

Task Endpoints

Learn about task execution

Examples

View code examples

OpenAPI Spec

Download OpenAPI specification